Chuiyu Wiki

Appearance

2025-10-19
1617
6.5m

使用colcon 构建软件包 ​

1.使用colcon 构建软件包 ​

1.背景 ​

colcon是对ROS构建工具catkin_make、catkin_make_isolated、catkin_tools和ament_tools的改进。有关colcon设计的更多信息，请参阅此文档.

2.安装colcon ​
bash
sudo apt install python3-colcon-common-extensions
3.基础知识 ​

ROS工作空间是一个具有特定结构的目录。通常有一个 src 子目录。在该子目录下是ROS软件包的源代码所在位置。通常该目录开始时为空。

colcon进行外部构建。默认情况下，它会创建以下目录作为 src 目录的同级目录：

  • build 目录将用于存储中间文件。对于每个软件包，将在其中创建一个子文件夹，例如在该子文件夹中调用 CMake。

  • install 目录是每个软件包将要安装到的位置。默认情况下，每个软件包将被安装到单独的子目录中。

  • log 目录包含有关每个 colcon 调用的各种日志信息。

注解

与 catkin 相比，没有 devel 目录。 catkin是ROS1中的编译工具。

4.创建一个工作空间 ​

首先，创建一个目录（ros2_ws）来容纳我们的工作空间：

bash
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

此时，工作空间中只包含一个空目录 src：

bash
.
└── src

1 directory, 0 files
5.添加一些源文件 ​

将 examples 存储库克隆到工作区的 src 目录中：

bash
git clone https://github.com/ros2/examples src/examples -b humble

现在工作区应该有 ROS 2 示例的源代码：

bash
.
└── src
    └── examples
        ├── CONTRIBUTING.md
        ├── LICENSE
        ├── rclcpp
        ├── rclpy
        └── README.md

4 directories, 3 files
6.源目录 ​

很重要的是，我们已经为现有的 ROS 2 安装环境提供了所需的构建依赖项，以便为示例软件包提供支持。这可以通过对二进制安装或源码安装提供的设置脚本进行实现，即使用另一个 colcon 工作区提供的设置脚本（参见 Installation）。我们称这个环境为 源目录。

我们的工作空间ros2_ws将作为现有ROS 2安装的覆盖层。一般而言，建议在计划迭代少量软件包时使用覆盖层，而不是将所有软件包放入同一个工作空间中。

7.构建工作空间 ​

注意 要在Windows上构建软件包，您需要处于Visual Studio环境中，请参阅 构建ROS 2代码 获取更多详细信息。

在工作空间的根目录下运行colcon build命令。由于ament_cmake等构建类型不支持devel空间的概念，而且需要安装软件包，因此colcon支持选项--symlink-install。这允许通过更改source空间中的文件（例如Python文件或其他非编译资源）来更改已安装文件，以便实现更快的迭代。

bash
colcon build --symlink-install

在构建完成后，我们应该能够看到 build、install 和 log 目录：

bash
.
├── build
├── install
├── log
└── src

4 directories, 0 files
8.运行测试 ​

为了对刚刚构建的软件包运行测试，请执行以下操作：

bash
colcon test
9.加载环境变量 ​

当colcon成功构建完成后，输出将位于install目录中。在您可以使用任何已安装的可执行文件或库之前，您需要将它们添加到您的路径和库路径中。colcon会在install目录中生成bash/bat文件来帮助设置环境。这些文件将会将所有所需的元素添加到您的路径和库路径中，并提供由软件包导出的任何bash或shell命令。

bash
source install/setup.bash
10.试用演示 ​

在环境配置完成后，我们可以运行由colcon构建的可执行文件。让我们从示例中运行一个订阅者节点：

bash
ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

在另一个终端中，让我们运行一个发布者节点（不要忘记配置脚本）：

bash
ros2 run examples_rclcpp_minimal_publisher publisher_member_function

你应该能够看到发布者和订阅者的消息，并且消息编号会递增。

11.创建你自己的包 ​
colcon使用在`REP 149 <[https://www.ros.org/reps/rep-0149.html](https://www.ros.org/reps/rep-0149.html)>`__中定义的``package.xml``规范（也支持`format 2 <[https://www.ros.org/reps/rep-0140.html](https://www.ros.org/reps/rep-0140.html)>`__）。

colcon支持多种构建类型。推荐的构建类型是``ament_cmake``和``ament_python``。还支持纯``cmake``包。

[``](http://fishros.org/doc/ros2/humble/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.html#id1)ament_python``构建的一个示例是`ament_index_python包 <[https://github.com/ament/ament_index/tree/humble/ament_index_python](https://github.com/ament/ament_index/tree/humble/ament_index_python)>`__，其中setup.py是构建的主要入口点。

诸如`demo_nodes_cpp <[https://github.com/ros2/demos/tree/humble/demo_nodes_cpp](https://github.com/ros2/demos/tree/humble/demo_nodes_cpp)>`__的包使用``ament_cmake``构建类型，并使用CMake作为构建工具。

为了方便起见，您可以使用ros2 pkg create工具基于模板创建一个新的包。

12.设置 `colcon_cd ​

命令 colcon_cd 允许您快速将当前工作目录更改为包的目录。例如，colcon_cd some_ros_package 可快速将您导航到目录 ~/ros2_ws/src/some_ros_package。

bash
echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/opt/ros/humble/" >> ~/.bashrc

根据您安装 colcon_cd 的方式和工作空间的位置，上述说明可能有所不同，请参考 文档 以获取更多详细信息。要在Linux和macOS上撤消此操作，请找到系统的shell启动脚本并删除附加的source和export命令。

13.设置 colcon 的选项自动补全 ​

如果已安装 colcon-argcomplete 包，则命令 colcon 支持命令补全，适用于 bash 和类似 bash 的 shell。

bash
echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash" >> ~/.bashrc

根据您安装 colcon 的方式和工作空间的位置，上述说明可能会有所不同，请参考 文档 获取更多详细信息。要在 Linux 和 macOS 上撤消此操作，请找到您系统的 shell 启动脚本并删除附加的源命令。

14.提示 ​

  • 如果您不想构建特定的软件包，请在目录中放置一个名为“COLCON_IGNORE”的空文件，它将不会被索引。

  • 如果您想避免在CMake软件包中配置和构建测试，您可以传递参数：--cmake-args -DBUILD_TESTING=0。

  • 如果您想从软件包中运行单个特定测试：

bash
colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG
最近更新